home *** CD-ROM | disk | FTP | other *** search
/ Risc World 5 / Risc World 5.iso / SOFTWARE / Issue5 / PD / FLOWER / TINCT009 / !Help next >
Text File  |  2004-11-02  |  11KB  |  252 lines
  1. Tinct
  2. =====
  3. This module provides the necessary functionality to display alpha-blended
  4. sprites both scaled and otherwise. It also provides functions for dithering,
  5. error diffusion and performing bi-linear filtering to improve their appearance.
  6.  
  7.  
  8. Technical information
  9. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  10. To ensure future compatibility, this module does not patch the OS in any way
  11. and works in a totally legal way. It also does not write to itself in any
  12. way, so is suitable for running from ROM.
  13.  Redirection to sprites is supported, although due to the overheads involved
  14. with caching the colour translation tables it is not recommended that this is
  15. done frequently. There are some exceptions to this, however, as redirecting to
  16. a 16bpp or 32bpp mode sprite does not require any translation tables, and
  17. redirecting to a sprite that has the same mode and palette as the previous
  18. destination that Tinct was used for causes a minimum overhead as the
  19. translation tables are checked and cached values are used if possible.
  20.  
  21. Format of a sprite with 8-bit alpha channel
  22. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  23. The sprite format used by Tinct differs from those used by RISC OS Select,
  24. and whilst facilities are supplied to convert sprites into the required format,
  25. no facilities are provided to manipulate them.
  26.  All sprites used by Tinct must be 32bpp, and cannot have a standard RISC OS
  27. mask specified. The basic format of the sprite is shown below, with the
  28. restrictions to the standard sprite format marked with an asterisk (*):
  29.  
  30.     [+0]    Offset to next sprite
  31.     [+4]    Sprite name, up to 12 characters with trailing zeroes
  32.     [+16]    Width in words - 1
  33.     [+20]    Height in scan lines - 1
  34.     [+24]     First bit used
  35.     [+28]     Last bit used
  36.     [+32]    Offset to sprite image
  37.     [+36] *    Offset to sprite image (no mask allowed)
  38.     [+40] *    Sprite type (must be 0x301680B5)
  39.  
  40. Whereas for normal sprites the sprite image would be a series of colour words
  41. of the format RrGgBb00, alpha-blended sprites use the empty byte to specify
  42. the alpha value, ie RrGgBbAa.
  43.  The alpha values represent the blending level on a linear scale where 0x00
  44. represents that the source pixel is totally transparent and 0xff that it is
  45. totally opaque. It should be noted that as a standard 32bpp sprite (eg as
  46. created with !Paint) will have the alpha channel set to 0x00 by default no
  47. output will be visible when plotting as an alpha-blended sprite.
  48.  
  49. Error handling
  50. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  51. If an incorrect sprite is attempted to be used, Tinct currently always returns
  52. error number 0x700 (SBadSpriteFile) rather than the specific cause of the
  53. problem (eg. BadDPI, BadMSFlags or BadPixelDepth) as OS_SpriteOp would do.
  54. There are several technical reasons for this behaviour, and future versions of
  55. Tinct may return more descriptive errors depending on the cause.
  56.  
  57.  
  58. SWIs provided
  59. ¯¯¯¯¯¯¯¯¯¯¯¯¯
  60. Tinct provides four SWIs to plot sprites and one to convert sprites to their
  61. 32bpp equivalent. All values supplied to Tinct must be in OS units, and the
  62. current OS clipping rectangle is used.
  63.  The sprite pointers provided are equivalent to calling OS_SpriteOp with
  64. bit 9 of the reason code set. To plot a sprite by name, the sprite should
  65. first be found by using OS_SpriteOp with reason code 0x18 and using the
  66. returned sprite address.
  67.  
  68. Tinct_PlotAlpha (0x57240)
  69. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  70. Plots an alpha-blended sprite at the specified coordinates.
  71.  
  72. ->    R2    Sprite pointer
  73.     R3    X coordinate
  74.     R4    Y coordinate
  75.     R7    Flag word
  76.  
  77.  
  78. Tinct_PlotScaledAlpha (0x57241)
  79. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  80. Plots a scaled alpha-blended sprite at the specified coordinates.
  81.  
  82. ->    R2    Sprite pointer
  83.     R3    X coordinate
  84.     R4    Y coordinate
  85.     R5    Scaled sprite width
  86.     R6    Scaled sprite height
  87.     R7    Flag word
  88.  
  89.  
  90. Tinct_Plot (0x57242)
  91. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  92. Plots a sprite at the specified coordinates with a constant 0xff value for
  93. the alpha channel, ie without a mask.
  94.  
  95. ->    R2    Sprite pointer
  96.     R3    X coordinate
  97.     R4    Y coordinate
  98.     R7    Flag word
  99.  
  100.  
  101. Tinct_PlotScaled (0x57243)
  102. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  103. Plots a scaled sprite at the specified coordinates with a constant 0xff value
  104. for the alpha channel, ie without a mask.
  105.  
  106. ->    R2    Sprite pointer
  107.     R3    X coordinate
  108.     R4    Y coordinate
  109.     R5    Scaled sprite width
  110.     R6    Scaled sprite height
  111.     R7    Flag word
  112.  
  113.  
  114. Tinct_ConvertSprite (0x57244)
  115. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  116. Converts a paletted sprite into its 32bpp equivalent. Sufficient memory must
  117. have previously been allocated for the sprite (44 + width * height * 4).
  118.  As sprites with 16bpp or 32bpp do not have palettes, conversion cannot be
  119. performed on these variants. All sprites must be supplied with a full palette, 
  120. eg 8bpp must have 256 palette entries.
  121.  
  122. ->    R2    Source sprite pointer
  123.     R3    Destination sprite pointer
  124.  
  125.  
  126. Tinct_AvailableFeatures (0x57245)
  127. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  128. Returns the features available to the caller by specifying bits in the flag
  129. word. The features available are unique for each mode, although the current
  130. version of Tinct supports the same subset of features for all modes.
  131.  
  132. ->    R0    Feature to test for, or 0 for all features
  133. <-    R0    Features available
  134.  
  135.  
  136.  
  137. Flag word
  138. ¯¯¯¯¯¯¯¯¯
  139. All the SWIs provided by Tinct for plotting use a common flag word to
  140. describe the manner in which the plot is performed. Each bit controls a
  141. particular characteristic of the plotting:
  142.  
  143.     0  Forcibly read the screen base (only use if hardware scrolling)
  144.     1  Use bi-linear filtering when scaling sprites
  145.     2  Dither colours in 16bpp and below
  146.     3  Perform error diffusion if bit 2 clear, invert dither pattern if set
  147.     4  Horizontally fill the current graphics window with the sprite
  148.     5  Vertically fill the current graphics window with the sprite
  149.     6  Forcibly read the palette (only use if changing palette outside of
  150.        the WIMP)
  151.     7  Use OS_SpriteOp to perform final plotting (see note)
  152.     8+ Reserved (must be 0) if bit 7 is clear, background colour to
  153.        blend the alpha channel to otherwise
  154.  
  155. If a bit is set in the flag word that cannot be honoured by the current
  156. version of Tinct then it is ignored. Tinct_AvailableFeatures can be used
  157. to test in advance what flags will be honoured.
  158.  
  159. Bi-linear filtering
  160. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  161. Although bi-linear filtering is only relevant during scaled plotting, this
  162. situation occurs when the EigFactors of the mode are not equal. As such, an
  163. application should always set their preferred flags to ensure consistency. The
  164. case of XEig * 2 = YEig (rectangular pixel modes) for even height sprites is a
  165. special case and has optimised code implemented.
  166.  There is an upper limit to the size of sprite that can be bi-linear filtered.
  167. The checks that are currently made are:
  168.  
  169.     scaled_width / sprite_width < 256
  170.     scaled_height / sprite_height < 256
  171.     scaled_width * max(sprite_height, scaled_height) < 32,768
  172.  
  173.  It should be noted that as bi-linear filtering is performed as a pre-filter,
  174. it carries a sizable overhead. However, as all scaling calculations are
  175. performed during this filter, tiled plotting (bits 4 and 5) are affected by
  176. a smaller margin (in certain cases a speed gain can be achieved).
  177.  As bi-linear filtering is performed using a pre-filter, it can be used in
  178. association with OS_SpriteOp rendering.
  179.  
  180. Error diffusion and dithering
  181. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  182. If both error diffusion and dithering are enabled then the image is plotted
  183. using only dithering, but with the dither pattern inverted. This enables an
  184. application to provide the user with what appears to be a higher quality image
  185. by redrawing every frame with the flag toggled.
  186.  There is a significant speed difference between dithering and error diffusion,
  187. and Tinct does not support error diffusion in all colour depths. If error
  188. diffusion is requested, but cannot be performed by Tinct then dithering with
  189. an inverted pattern is used (as if bits 2 and 3 were set).
  190.  There is an upper limit to the size of sprite that Tinct can perform error
  191. diffusion on. This is currently set to a display width of 2047 pixels wide with
  192. an unlimited height. Any attempt to use a higher resolution will result in
  193. dithered rendering with an inverted pattern (ie bits 2 and 3 set).
  194.  As error diffusion and dithering are implemented during the plot cycle, it is
  195. not possible to use them in association with OS_SpriteOp rendering. However,
  196. the bits should be set as future versions of Tinct may respect them for users
  197. of RISC OS 3.1 where true colour sprites are not supported.
  198.  
  199. Sprite filling
  200. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  201. If filling is specified, then the supplied co-ordinate is the offset of the
  202. pattern relative to (0, 0) used for the fill. For example, a 64x64 sprite that
  203. is plotted with bits 4 and 5 set and a position of (32, 16) would fill the
  204. current graphics window with multiple copies of the image stating with the
  205. first image plotted at (-32, -48).
  206.  The caller should not concern itself with the size of the image being tiled
  207. as small images are internally optimised where possible to maximise the
  208. plotting speed.
  209.  
  210. Rendering using OS_SpriteOp
  211. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  212. It can be useful to use Tinct to perform the rendering to using OS_SpriteOp.
  213. There are two general situations where this may be useful:
  214.  
  215.     1) To output to a printer driver
  216.     2) To allow hardware acceleraton (such as a ViewFinder card)
  217.  
  218. By using Tinct rather than a direct OS_SpriteOp call, it allows the caller to
  219. retain certain features Tinct provides (such as sprite filling and a limited
  220. version of the standard alpha blending) and allows the caller to have a common
  221. plotting interface.
  222.  When using this feature for alpha-blended sprites, the background colour
  223. specified in the top 24-bits of the flag word is used for blending with any
  224. pixels that are not transparent. This requires that Tinct requires a second
  225. copy of the sprite in memory to modify which may present a significant overhead
  226. in some situations. Plotting opaquely does not have any such overheads.
  227.  Using OS_SpriteOp rendering does not currently work on RISC OS 3.1 or earlier
  228. due to the lack of support for true colour sprites. Future versions of Tinct
  229. may remove this restriction.
  230.  
  231. Contact details
  232. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  233. If you would like to report a problem relating to Tinct, provide feedback, or
  234. request a licence for a commercial product, please use the details below:
  235.  
  236. Address: 5 Queens Close, East Markham, Newark, Nottinghamshire, NG22 0QY. UK
  237. E-mail: info@tinct.net
  238. Website: www.tinct.net
  239.  
  240.  
  241. Copyright and licence details
  242. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  243. Tinct is © copyright Richard Wilson, 2004.
  244.  
  245. Distribution and usage
  246. ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
  247. Unrestricted use of Tinct is hereby granted for any non-commercial product. Any
  248. use as part of a commercial product requires written consent from the author.
  249. No charge may be made relating to the distribution of this software, and this
  250. file should be included in all copies of the software.
  251.  Modified versions of this program may not be distributed without the authors
  252. consent, nor may modified versions of the source code or relating files.